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ABSTRACT 

Documentation  as  an  affective  method  of  transferring 
information  between  individuals  in  order  to  reduce  software 
maintenance  costs  is  examined-  Various  categories  of  docu- 
mentation are  identified  and  evaluated  as  to  their  effec- 
tiveness toward  easing  the  maintenance  effort.  The  concept 
of  minimal  documentation  is  introduced  as  the  solution  to 
the  problem  of  determining  the  corrsct  amount  of  information 
reguired      for   a      specific  maintenance      task.  The   idea      of 

utilizing  an  explicit  documentation  hierarchy  as  the  ideal 
method  for  storing  explicit  documentation  is  proposed.  With 
the  proper  implementation  of  the  documentation  hierarchy, 
the  minimal  documentation  concept  can  be  realized,  and  the 
maintenance  effort    reduced. 
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I.    IHTRODOCTIDN 

A.  THE    FHOBLEH 

There  is  much  discussion  in  the  software  engineering 
literature  concerning  the  overwhelming  cost  of  software 
maintenance.  It  has  been  indicate!  that  in  sone  systems  up 
to  eighty  percent  of  the  cost  of  a  software  system  is 
consumed  in  the  maintenance  phase  of  the  software  life  cycle 
[Ref.  1  ].  In  order  to  properly  maintain  the  software,  it 
must  be  properly  documented.  Often  the  same  person  does  not 
perform  tasks  in  all  phases  of  the  Life  cycle,  thus  without 
documentation,  continuity  between  the  phases  can  be  lost. 
Sometimes  the  only  interface  between  each  phase  is  a  piece 
of  documentation.  This  points  out  the  criticaiity  of  docu- 
mentation in  the  software  life  cycle;  if  the  documentation 
between  phases  is  not  done  well,  mu.ch  of  the  work  on  the 
project    must  be    recreated   for   subsequent   phases. 

B.  PURPOSE    AND    APPROACH 

There  is  a  lack  cf  cohesive  disoussion  in  current  liter- 
ature concerning  proper  documentation  for  efficient  software 
maintenance.  Because  of  the  treasndous  cost  involved  with 
software  maintenance,  an  attempt  to  ease  the  maintenance 
effort  needs  to  be  made  through  the  use  of  adequate 
documentation. 

The  purpose  of  this  thesis  is  to  address  documentation 
as  a  method  of  information  transfer  throughout  the  life 
cycle  of  a  software  project  in  the  support  of  software  main- 
tenance. Various  types  of  documentation  are  discussed  and 
evaluated  as  to  their  effectiveness  toward  easing  the  main- 
tenance  effort.         An    attempt   is   made    to    determine    the   proper 


type  and  amount  of  information  needed  to  effectively  main- 
tain the  software  project.  An  effort  is  made  to  categorize 
and  quantify  different  aspects  of  documentation  based  en 
task  and  user  needs.  The  concept  of  a  documentation  hier- 
archy is  put  forth  as  a  method  for  organizing  these  aspects. 
The  idea  is  to  give  the  receiver  of  that  information 
precisely  the  amount  of  information  required  to  complete  the 
maintenance   task.  Too  much   information      can   bog      one   down 

with  unnecessary  details  while  too  little  information  car- 
cause  one  to  waste  many  hours  in  trying  to  understand  the 
program.  Thus  a  solution  to  the  problem  of  accessing  the 
exact   quantity    of  documentation   is  offered. 

Chapter  I  gives  an  overview  of  the  documentation  problem 
as  it  relates  to  software  maintenanoe.  A  description  of  the 
approach  for  the  thesis  is  given  along  with  some  general 
definitions  of  terms  used  in  the  software  maintenance  envi- 
ronment. Also,  the  idea  of  minimal  documentation  is  intro- 
duced   in   this   chapter. 

Chapter  II  discusses  software  maintenance  in  detail 
with  a  look  at  the  software  life  cyole.  A  software  project 
scenario  is  described  to  set  basic  guidelines  for  the 
thesis.  The  different  types  of  maintenance  as  they  relate 
to  the  software  modification  task  are  described  along  with 
the  identification  of  some  of  the  oauses  and  solutions  for 
the    software  maintenance   problem. 

Chapter  III  introduces  the  idea  of  the  transfer  of 
knowledge  between  individuals  as  being  the  goal  of  effective 
documentation.  This  knowledge  transfer  is  accomplished  by 
utilizing  various  methods  for  recording  information. 
Documentation  is  then  categorized  according  to  the  type  of 
information  that  is  conveyed  and  also  according  to  depen- 
dencies fcased  on  a  person's  skill  and  position  on  the  main- 
tenance team.  Finally,  the  role  of  documentation  for  a 
project   is    discussed- 


Chapter  IV  introduces  the  con:epu  of  a  documentation 
hierarchy  in  support  of  minimal  documentation.  The  levels 
of  the  hierarchy  are  based  on  the  level  of  detail  contained 
in  the  documentation.  The  various  users  of  the  documenta- 
tion need  only  to  access  the  proper  level  in  the  documenta- 
tion hierarchy  in  order  to  have  the  minimal  documentation 
that    is   required   for   the  completion   of   the    task   at   hand. 

Chapter  7  discusses  the  effectiveness  of  several 
specific  forms  of  documentation  in  relation  to  the  perform- 
ance of  the  maintenance  task.  The  evaluation  is  made  that 
there  is  not  a  "bes-"  form  of  documentation  for  all  mainte- 
nance tasks.  The  most  effective  documentation  form  varies 
with  the  maintenance  task  and  the  type  of  programming 
processing    (sequential   or  concurrent)     being   used. 

Chapter  71  consists  of  the  thesis  conclusions  and 
recommer.dat  ions. 

C.    DEFINITIONS 

Certain  basic  definitions  are  needed  in  order  to  prop- 
erly address  the  issue  of  software  documentation  as  it 
relates  to  software  maintenance.  For  the  purposes  of  this 
thesis,  software  maintenance  will  be  considered  to  be  the 
process  of  updating  and  correcting  a  software  system  once 
the    project   is    delivered  and   made   operational. 

Software  documentation  is  the  recorded  information  that 
can  be  used  to  transfer  information  and  ideas  from  one 
person  to  another.  Unlike  software  maintenance,  which  has 
been  defined  to  begin  after  the  project  is  delivered,  soft- 
ware documentation  is  produced  throughout  the  entire  soft- 
ware life  cycle  from  the  conceptual  phase  to  the  support 
phase.  Since  documentation  follows  the  evolution  of  a  soft- 
ware system,  adequate  and  reliable  documentation  is  inva- 
luable  when   it    comes    to   maintaining   the   system. 
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Minimal  documentation  is  defined  as  the  exact  amount  of 
documentation  on  a  project  that  is  required  by  the  receiver 
to   accomplish  the   receiver'  s   task.  Whan    the  minimal    iocu- 

mentation  concept  is  used,  only  the  precise  amount  of  docu- 
mentation that  is  needed  is  accessed,  and  the  receiver  is 
not  forced  to  wade  through  unnecessary  information.  Just 
enough  information  is  recorded  so  that  the  receiver  is  able 
to  proceed  with  the  job  at  hand.  This,  then,  is  an  idea  of 
documentation  efficiency  with  no  more  and  no  less  informa- 
tion   being   exposed    tc  the   receiver  than    is    actually   needed. 

Maintainability  is  a  term  that  must  be  clarified. 
Martin  and  McClure  (Ref,  2  ]  define  maintainability  as  the 
"ease  with  which  a  software  system  can  be  corrected  when 
errors  or  deficiencies  occur,  and  can  be  expanded  or 
contracted  to  satisfy  new  requirements."  Maintainability  of 
a  software  system  can  be  enhanced  with  the  availability  of 
adequate   minimal   documentation. 

Onderstandability  is  considered  to  be  one  of  the  mos- 
important  concepts  in  the  realm  of  maintainability.  Martin 
and  McClure  define  under sta ndability  as  "the  ease  with  which 
we  can  understand  the  program  purpose  and  how  the  program 
achieves  its  purpose".  Since  documentation  transfers  infor- 
mation concerning  software  system  evolution,  the  minimal 
documentation  concept  aids  in  the  achievement  of  program 
understandability. 
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II.     THE    SOFTWARE    HAINTEHAHCE    PROBLEH 

A.       THE    SOFTWARE   LIFE  CYCLE 

The  development  of  a  software  project  goes  through 
several  phases  from  conception  to  actual  system  operation. 
This  development  process  is  called  the  software  life  cycle. 
There  are  several  mcdels  available  to  represent  the  soft- 
ware life  cycle.  The  one  used  by  the  Department  of  Defense 
as  indicated  in  Department  of  Defense  Instruction  5000.1  is 
presented  in  Figure  2.1.  It  gives  a  reasonable  representa- 
tion of  most  simple  models.  An  advantage  of  this  model  is 
that  each  major  phase  is  broken  into  its  subsequent 
subphases.  This  model  is  general  enough  to  be  applied  to 
most  software  systems,  with  the  dstails  being  left  to  the 
specific   project. 

Documentation  must  be  carried  throughout  the  life  cycle 
in  order  to  promote  understandabiiity  in  subsequent  phases. 
Ultimately,  the  ideal  documentation  contains  enough,  informa- 
tion such  that  when  the  program  is  completed  and  is  opera- 
tional,   it    can    be   maintained   effectively. 

The  major  problem  with  the  Department  of  Defense  model 
is  the  implication  that  is  given  concerning  the  flew  of  the 
software  life  cycle.  One  is  left  with  the  idea  that  as  one 
phase  abruptly  halts,  the  next  phase  begins.  In  practice, 
the  phase  boundaries  are  somewhat  obscure.  Quite  often  work 
on  one  part  of  a  phase  begins  before  all  work  in  a  previous 
phase  is  completed.  Also  one  gets  the  impression  that  there 
are   no      interdependencies  between   the    phases.  In   reality, 

decisions   made    in  one  phase      often   directly   affect      the   work 
of    a      subsequent  phase.  This   makes        each   phase      somewhat 

dependent   upon      decisions   made  in      a    previous      phase.        Also 
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there  are  times  when  a  decision  made  in  oae  phase  is 
determined  to  be  unrealistic  by  restrictions  or  actions 
taken  in  a  following  phase.  Therefore,  a  feedback  mechanism 
is  needed  to  carry  information  between  phases  in  order  to 
keep    the  software   project  development   moving. 

Documentation  is  the  method  of  recording  information 
that  is  to  be  transferred  forward  and  backward  to  aid  in 
software   modification.  Figure    2.2    gives   a      more   realistic 

view  cf  the  software  cycles  indicating  some  of  the  phase 
interrelationships   ( Ref .    3]. 

Figure  2.2  shows  validation  ani  verification  subphases 
in  the  requirements  and  design  phases  of  -he  cycle.  This  is 
important  because  each  phase  should  be  verified  as  being 
possible  and  feasible  as  early  in  the  cycle  as  possible  in 
order  to  avoid  unnecessary  work.  For  example,  it  would  be 
wasteful  to  work  through  to  the  implementation  phase  only  to 
find  out  that  the  project  was  never  feasible  in  the  first 
place. 

Studies  indicate  that  the  most  economical  time  to  catch 
and  correct  a  problem  is  as  early  in  the  development  cycle 
as  possible.  The  cost  of  detecting  and  correcting  an  error 
more  than  doubles  for  each  phase  through  which  it  passes 
undetected.  This  rate  of  cost  increase  holds  true  for  each 
subsequent  phase  through  which  the  problem  passes  without 
detection.      [Ref-    3]   and  [Ref.    ft]. 

While  the  simplistic  view  presented  in  Figure  2. 1  is 
relatively  easy  to  comprehend,  it  is  extremely  important  to 
remember  the  interrelationships  between  the  various  phases 
as  indicated  by  Figure  2.2.  With  those  interrelationships 
being  kept  in  mindr  the  simplified  life  cycle  model  shown  in 
Figure    2.1    will    be    adequate    for   use    in   this   thesis. 
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Figure   2.2       The  laterfall    Hodel   of   the   Software   Life-cycle. 

15 


B.       THE    SOFTWIHE   PROBLEM 

Bohem  [Hef.  3]  gives  us  some  insights  into  the  magnitude 
of  the  economics  involved  with  the  software  problem.  The 
annual  cost  of  software  for  the  United  States  in  1980  was 
about  2  percent  cf  the  Gross  National  Product.  The  cost  is 
expected  to  grow  faster  than  the  general  rate  of  the  economy 
thus  representing  an  even  larger  proportion  of  the  Gross 
National  Product  as  time  goes  on.  The  portion  of  the  effort 
spent  on  software  maintenance  has  increased  faster  than  the 
effort  spent  on  software  development.  With  the  growth  of 
software  maintenance  taking  such  a  large  portion  of  the 
total  cost  of  a  system,  it  would  be  wise  to  find  ways  to 
enhance   the   efficiency  of  the   maintenance   effort. 

Along  with  the  economic  issues  of  software  maintenance, 
we  must  look  at  the  social  aspects  of  computers  as  they 
relate  to  software.  Things  such  as  computerized  billing  and 
banking  have  made  a  permanent  impact  upon  the  lives  of  most 
Americans.  An  increasing  number  of  workers  in  the  United 
States  will  be  relying  on  computers  to  perform  tasks 
involved  with  their  daily  work.  By  1985  it  is  predicted 
that  approximately  U0  percent  of  th=  working  population  will 
fall  into  that  category.  With  this  kind  of  computer  and 
software  proliferation,  there  will  be  continued  growth  in 
the  amount  cf  software  that  is  needed.  This  growth  of  soft- 
ware translates  into  a  significant  amount  of  necessary 
software  maintenance  as  both  the  software  system  and  the 
state   of  technology    change. 

As  the  need  for  software  maintenance  increases,  it 
becomes  imperative  that  maintenance  efficiency  be  improved. 
The  idea  of  using  minimal  documentation  in  order  to  improve 
understandability,  which  in  turn  aids  maintainability,  is 
seen  as  a  way  to  increase  the  efficiency  of  the  software 
maintenance  effort. 
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1 .      Scenario 

There  are  many  types  of  programs  that  are  developed 
ranging  from  very  small  to  very  large,  and  the  size  of  a 
program  can  determine  the  software  documentation  issues 
related   to      that   particular    program.  In   order      to    address 

specific  documentation  issues  we  nead  to  focus  on  a  partic- 
ular   Scenario. 

The  program  with  which  we  will  be  concerned  is  one 
of  medium  length  involving  thirty  to  forty  thousand  lines  of 
code.  It  is  a  software  program  that  is  to  be  maintained,  so 
it  is  neccessary  that  software  documentation  be  generated. 
(If  a  program  were  never  to  be  modified,  than  documenta- 
tion would  not  be  necessary.)  For  the  purpose  of  this 
thesis,  the  program  code  is  not  considered  to  be  a  form  of 
documenxation.  The  program  is  one  that  was  developed  by  a 
software  development  team  (as  opposad  to  being  developed  by 
a  solo  programmer)  with  documentation  maintained  throughout 
the  development.  The  development  followed  the  basic  guide- 
lines as  indicated  in  tha  Department  of  Defense  life  cycle 
model  (Figure  2. 1)  .  The  program  developers  are  not  the  end 
users  of  the  system.  The  program  is  embedded  in  an  environ- 
ment   that   is  subject    to    change. 

When  a  modification  to  the  system  is  required,  a 
change        request        protocol         is  followed        in        which      a 

requested  change  is  considered  and  a  determination  is  made 
as  to  whether  the  change  should  be  incorporated  into 
the    existing  system.  If    the   change    is   to   be     made,      it   is 

acted  upon  by  a  designated  maintenance  team.  The  personnel 
assigned  to  the  maintenance  team  may  or  may  not  have  other 
collateral  duties  in  the  organization,  and  they  may  or  may 
not  have  had  any  connection  with  the  original  development  of 
the  system.  Emergency  changes  are  implemented  as  quickly  as 
possible  while  routine  modificatioas  are  implemented  in  an 
annual  system   update. 
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The  system  is  considered  to  have  a  lifa  expectancy 
cf  approximately  twenty  years,  and  it  is  farther  assumed 
that  the  system  has  been  in  operation  for  several  years  with 
maintenance  being  accomplished  and  documentation  being 
updated   accordingly. 

2.      Understandability 

Understandability  is  considered  to  be  one  of  the 
most  important  concepts  in  the  realm  of  maintainability.  If 
a  piece  of  software  that  is  to  be  maintained  proves  to  be 
both  efficient  and  successful,  yet  is  not  understandable  to 
the  maintainers,  it  can  be  difficult  and  expensive  (if  net 
impossible)    to      modify     to    meet   changing   needs. 

In  a  good  system,  there  is  information  available  as 
to  the  purpose  cf  the  system,  the  proper  use  of  the  system, 
and    the      proper    maintenance      of  the      system  [ 2ef .    2].  All 

phases  of  the  life  cycle  will  have  accompanying  documenta- 
tion concerning  the  development  at  each  stage  of  the  system, 
and  that  documentation  will  carry  the  required  informa- 
tion   that   aids    in   the  understandability   of    the  program. 

Familiarity  is  a  factor  that  helps  determine  the 
effectiveness  and  understandability  of  a  program.  A  person 
who  is  very  familiar  with  the  code  and  the  functioning  of 
the  system  would  probably  not  have  great  difficulty  in 
understanding  the  system,  even  if  the  documentation  were 
somewhat  lacking  in  quality  and  the  system  itself  were  very 
complex.  On  the  other  hand,  the  inexperienced  or  unfamiliar 
maintainer  would  probably  have  difficulty  in  understanding 
the    program.  we    will   see    later      how   the   factor      of   famil- 

iarity determines  fcr  an  individual  the  level  of  detail 
needed  in   the   documentation. 

Martin      and        McClure      state  that      understandable 

programs  generally  have  several  common  characteristics: 
struct uredness ;    consistency;   completeness;    conciseness;      and 
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documentation.  Each     of      these     characteristics      will     be 

discussed   in  more  detail. 

a.  Structuredness 

The  effective  structuring  of  a  program  increases 
understanding      by  standardizing      tha      program   format.  The 

standardization  will  set  restrictions  and  guidelines  en  the 
logical  flow  of  the  program.  Program  modules  will  be  set  up 
in  a  hierarchical  manner  with  the  order  of  execution  deter- 
mined by  the  guidelines.  The  use  of  these  guidelines  for 
program  construction  will  provide  a  consistent  logic  that 
will    aid  the  understandability   of    the    overall   system. 

b.  Consistency 

A  program  should  be  written  in  a  consistent 
style  in  accordance  with  established  programming  standards. 
The  structuredness  mentioned  above  oan  be  considered  to  be  a 
method  of  developing  a  consistent  style.  It  is  difficult  to 
understand  a  program  in  which  the  style  of  writing  does  not 
follow  a  common  method  of  construction.  This  is  sometimes 
difficult  to  accomplish  when  several  members  work  together 
as  a  team  on  a  project  unless  close  communication  control  is 
maintained.  Consistent   types      of   comments      must   be      main- 

tained. When  a  module  is  described,  it  should  handle  the 
description  of  the  piece  of  code  the  same  way  every  other 
module  is  handled  in  terms  of  the  amount  of  detail  discussed 
and  the  order  in  which  the  information  is  provided. 
Variable  names  should  be  selected  with  the  same  sort  of 
reasoning  throughout  the  program,  and  the  program  should  be 
consistent  with  the  design  instructions.  In-line  comments 
should  be  used  to  clarify  coding  statements,  and  this  prac- 
tice should  be  consistent  throughout  the  program.  There 
should  be  no  visible  evidence  that  the  program  was  not 
written  by  one  person  with  a  consistent  train  of  thought 
throughout    the    development    process. 
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c.  Completeness 

A  complete  program  has  all  of  its  components 
available  to  use  and  to  bs  perused  by  the  maintainer.  The 
maintenance  person  must  be  able  to  access  all  parts  of  the 
program  that  are  related  to  the  maintenance  function  if 
understandability  is  to  be  accomplished.  Any  variables  or 
modules  should  be  included  in  a  cross-reference  scheme  so 
that  the  maintainer  can  trace  a  program  component  throughout 
the  system.  Every  unusual  feature  in  the  program  should  be 
clearly  explained,  and  error  messages  should  be  made 
understandable. 

d.  Conciseness 

k  concise  program  is  one  that  uses  only  the 
coding  necessary  to  achieve  the  design  requirements  with  no 
extra  (perhaps  unused)  pieces  of  code.  Every  piece  of  code 
must  be  reachable  by  some  action  of  the  program.  Unused 
variables  and  duplicate  functions  should  be  nonexistent  and 
comments  should  not  be  excessively  verbose  or  cryptic  in 
meaning.  Understandability  decreases  when  complexity  over- 
takes simplicity.  The  system,  though  it  in  itself  may  be 
complex,  can  be  simplified  through  the  proper  use  of 
conciseness   principles. 

e.  Document ation 

Perhaps  the  concept  that  pulls  all  of  the  above 
understandability  methods  together  is  the  development  (and 
use)       of   good   documentation    techniques.  The  use   of   all   of 

the  above  ideas  that  promote  understandability  in  a  system 
may    not   in   themselves  be   successful. 

The  structuredness  of  a  program  oust  be  docu- 
mented in  such  a  way  that  the  structurization  methods  are 
understood  by  the  maintainers.  The  consistent  program  must 
have    the      modules   described    and      documented   in     a    consistent 
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way.  Comments  should     ba      arranged      near   each      module     to 

describe  the  module  in  some  detail.  The  modile  comments 
should  include  the  purpose  of  the  module,  the  variables  used 
or  modified  in  the  module,  and  a  description  of  the  output 
of  the  module.  The  module  description  should  indicate  the 
relative  postion  of  the  module  with  respect  to  other  modules 
in  the  program  to  give  some  idea  as  to  how  the  module  was 
reached   and   how    it   fits   into   the    program   hierarchy. 

Documentation  also  aids  understandability  by 
containing  information  as  to  the  completeness  of  the 
program.  Information  is  recorded  as  to  how  a  module  of  the 
program  is  reached  and  how  each  module  is  related  in  the 
overall  system  scheme.  Proper  documentation  should  also  be 
concise  with  only  the  necessary  information  being  provided 
to  the  maintainer  so  as  to  enhance  unders-andability  without 
confusion. 

3.      Maintenance    Effort 

Since  the  maintenance  effort  represents  such  a  large 
portion  of  the  overall  cost  of  a  software  system,  a  look  at 
the  software  maintenance  effort  and  ways  in  which  to  make 
this  effort  efficient  by  means  of  minimal  documentation  is 
in   order. 

A  survey  of  data  processing  maintenance  activities 
by  Lient2  and  Swanscn  [Ref.  5]  shows  that  only  half  of 
the  people  who  are  assigned  to  maintain  programs  actually 
worked  on  their  development.  This  fact  is  significant  in 
that  a  lack  of  continuity  of  the  original  thinking  occurs. 
To  make  matters  worse,  the  number  of  development  personnel 
assigned  to  the  maintenance  effort  diminishes  even  further 
as  the  life  of  a  software  system  is  extended.  Good  docu- 
mentation passes  information  about  the  program  between  those 
personnel  developing  the  program  and  those  maintaining  the 
program,    thus  preserving  the  continuity   of   thought. 
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In  order  to  gauga  the  magnitude  of  the  maintenance 
effort,  Lientz  and  Swanson  describe  the  effort  as  the  result 
of  the  combination  of  four  variablas:  system  age;  system 
size;  relative  amount  of  routine  debugging;  and  the  relative 
development  experience  of  the  maintsnance  personnel.  As  the 
system  age  extends,  the  system  size  tends  to  increase 
leading  to  a  greater  maintenance  effort.  With  an  increase 
in  system  size,  the  system  tends  to  naad  mora  routine  debug- 
ging, again  increasing  the  maintenance  effort.  When  the 
system  age  increases,  thare  is  also  an  increasing  amount  of 
personnel  turnover  which  leads  to  the  declining  relative 
development  axperiance  of  the  maintainors,  thus  again 
causing  an  increase  in  tha  maintenance  effort.  This  mainte- 
nance effort  increase,  of  course,  results  in  a  rise  of 
overall   maintenance    costs. 

Minimal  documentation  can  be  used  as  a  means  to 
promote  program  understandability  which  will  make  the  main- 
tenance effort  become  more  efficient,  and  in  turn  cause  a 
decrease   in   software    maintenance   costs. 

**  •      Types   of   Maintenance 

Generally  software  maintenance  can  be  divided  into 
three   categories:  corrective;      adaptive;        and    perfective 

maintenance  [Ref.  6 J.  Corrective  maintenance  is  considered 
to   be      purely   the      correction   of      software   errors.  Though 

corrective  maintenance  is  traditionally  seen  as  the  most 
obvious  type  of  maintenance  task,  it  is  interesting  to  note 
that  the  time  spent  solely  on  the  correction  of  errors 
amounts  to  only  seventeen  to  twenty-five  percent  of  the 
maintenance   person's    time  [Ref.    5]  and  [Ref.    7]. 

Adaptive  maintenance  is  considered  to  be  the  process 
of  adapting  or  changing  the  software  to  meet  the  environ- 
mental constraints  of  the  system.  An  adaptive  change  would 
be   considered  to   take  place    if      a   new   operating   system    is   to 
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be  installed  on  the  computer  that  is  used  by  the  program 
being  maintained.  This  area  of  maintenance  takes  up  about 
eighteen  to  twenty-five  percent  of  the  time  spent  on  mainte- 
nance [ Ref .    7]. 

Perfective  maintenance  concerns  the  "perfecting"  of 
the  system  by  making  user-requested  changes  to  the  software 
to  make  the  system  perform  "better".  It  is  interesting  to 
note  that  while  the  perfective  maintenance  activity  (some- 
times called  providing  enhancements}  does  not  involve  the 
act  of  correcting  errors,  it  takes  between  fifty  and  sixty 
percent  of  the  maintenance  person's  time--by  far  The  largest 
single  time  chunk  in  the  software  maintenance  effort 
[Ref,  7],  This  is  in  contrast  to  what  is  generally  consid- 
ered   to    be   "raai"    maintenance,    that   of   the    corrective   type. 

5.      Causes    of  Maintenance   Problems 

It  is  beneficial  to  look  at  some  of  the  things 
that  create  the  need  fcr  software  naintenance  and  ways  that 
the  use  of  proper  documentation  can  ease  the  maintenance 
task . 

Schneidewind  [Ref.  8]  indicates  that  several  items 
bring   about     maintenance   problems.  One    is     the    fact      that 

maintenance  is  often  viewed  by  both  designers  and  users  as  a 
task    that   is  not  very  glamorous.  Ihis   leads  to    a   tendency 

for  personnel  to  want  only  to  design  systems  while  letting 
the  maintenance  aspect  of  the  system  take  a  low  priority. 
This  leads  to  many  of  the  maintenance  problems  being  ignored 
during  the  development  phase,  including  the  proper  documen- 
tation of  the  project  as  it  progresses.  Maintenance  is 
often  not  even  considered  during  the  software  development 
process. 

In  reality,  documentation  and  maintenance  ideas  must 
parallel  system  development  through  all  of  the  software  life 
cycle   phases,      and      actually   become   an   integral      part   of  the 
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design  criteria.  This  is  necessary  if  a  program  is  to  be 
easily   understood  and  efficiently   operated   and   maintained. 

Glass  and  Nciseux  [Ref.  9]  show  that  a  traditional 
approach  to  the  software  problem  has  led  to  the  practice  of 
simply  tacking  on  maintenance  aids  as  an  afterthought.  The 
concept  of  software  maintenance,  particularly  in  something 
ether  than  that  of  a  corrective  nature,  seems  to  be  some- 
thing    that   receives    very  little    attention. 

Now  let's  lock  at  the  software  maintenance  problem 
as  viewed  by  managers  who  plan  the  maintenance  effort  based 
on   how   they     perceive  the   maintenance    problem.  Lientz    and 

Swanscn  [Ref.  5]  report  in  a  study  that  managers  perceive 
tha  lack  of  user  knowledge  as  by  far  the  most  dominant 
problem     in   the      maintenance      effort.  Following   the      user 

knowledge  problem  in  order  of  highest  to  lowest  significance 
were:  programmer  effectiveness;  product  quality;  programmer 
availabiltiy;  machine  requirements;  and  finally  system  reli- 
ability. When  the  system  is  properly  documented,  user 
knowledge  about  the  program  development  and*  maintenance 
techniques  can  be  increased.  Increased  knowledge  can  cause 
more  efficient  use  of  the  maintainors  time  thus  making  the 
maintainer  available  more  often  to  perform  other  tasks. 
Documentation  can  also  be  used  to  record  machine  require- 
ments in  such  a  way  that  they  are  made  available  for  consid- 
eration in  maintenance  decisions.  When  documentation  is 
used  properly,  it  can  reduce  these  problem  areas  as 
mentioned  and  result  in  an  overall  increase  in  system 
reliability. 

The  study  further  revealed  a  misconception  commonly 
held  by  managers.  Problems  were  perceived  by  managers  to  be 
greater  if  a  lot  of  corrective  maintenance  time  was  spent  on 
the  system.  As  mentioned  earlier,  corrective  maintenance  is 
not  the  big  time  consumer  whereas  perfective  maintenance 
does    in    fact  consume   the   bulk   of   the    maintainer's    time.        It 
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is  interesting  to  note  that  there  wara  no  significant  find- 
ings to  indicate  that  there  was  any  time  at  all  allotted  to 
the  maintenance  personnel  for  the  act  of  performing  purely 
perfective  maintenance.  When  it  is  understood  that  most  of 
the  actual  maintenance  time  is  spent  in  making  program 
enhancements  (that  is,  the  perfective  maintenance),  it 
becomes  clear  that  managers  need  to  re-evaluate  the  way  they 
allot   time    for    maintenance. 

Another  reason  for  maintsnance  problems  can  be 
considered  to  be  both  a  cause  and  a  result  of  the  above 
mentioned  problems.  This  reason  foe  maintenance  problems  is 
the  lack  of  good  documentation.  Schneidewind  points  out 
that  one  of  the  problems  involved  with  software  maintenance 
is  that  no  tracebility  is  built  into  the  software.  This 
problem  could  be  resolved  with  the  appropriate  documentation 
technigue.  In  order  to  convey  ideas  from  old  maintainers  to 
new  maintainers,  good  documentaion  is  needed.  For  example, 
formal  specifications  of  the  problem  for  which  the  system  is 
designed  must  be  presented  and  documented  so  that  a  later 
change  tc  the  program  can  be  evaluated  against  the  docu- 
mented reason  for  a  particular  design  system.  This  thesis 
will  explore  the  documentation  problem  in  more  detail  in 
later   chapters. 

6.      Solutions 

As  implied  from  the  above  discussion  of  the  causes 
of  the  software  maintenance  problem,  the  use  of  proper  docu- 
mentation  is  the   key   tc   many   maintenance   problem    solutions. 

The  solutions  require  the  cooperation  of  managers, 
users,  and  maintainers.  Good  maintenance  technigues  are 
also  necessary  and  must  begin  at  the  design  and  require- 
ments phases  of  the  life  cycle.  Several  ideas  are  presented 
by  Schneidewind  to  ensure  good  maintenance  practices  and 
good    documentation. 
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To  start,  good  maintenance  techniques  must  be 
planned   from      the  beginning      of  a      software   project.  This 

means  that  the  project  must  be  Assigned  with  maintenance 
integral  to  the  entire  life  cycle,  not  added  later  when  the 
project  is    completed.  Since   enhancements   take    up      most,   of 

the  maintenance  effort,  it  is  necessary  that  the  design 
ideas  incorporate  the  understanding  that  enhancements  will 
take      place  and      that,      managers     plan        maintenance     time 

accordingly. 

One  way  to  enhance  maintenance  personnel  under- 
standing is  to  use  modularity  techniques  in  the  design  of 
the  software  project.  This  means  that  common  ideas  or 
concepts  should  be  kept  together  in  a  logical  sense  that 
would  be  easy  for  the  maintainer  to  follow  utilizing  proper 
documentation.  The  documentation  should  be  able  to  convey 
the  module  concepts  used  in  the  dssign  of  the  software  to 
the    person    who    needs   to   make  software   modifications. 

Along  with  the  modularity  techniques,  the  idea  of 
independence  among  code,  data,  ani  data  base  is  in  order. 
This  independence  allows  certain  amounts  of  code,  functions, 
subroutines,  etc.  to  be  changed  without  devastating  effects 
taking  place  in  other  portions  of  the  program.  Information 
hiding  techniques  are  valuable  when  designing  a  program 
with    modular  independence  for   ease   of   maintenance. 

Schneidewind  also  gives  sevsral  ideas  concerning  the 
proper  development  of  documentation  along  with  the  project 
in  order  to  ensure  the  ease  of  maintenance.  Ons  idea  is  to 
design  the  documentation  first.  Many  a  programmer  knows  how 
bothersome  this  task  can  be.  Just  think  of  how  many  times 
the  flow  charts  or  refinement  procedures  were  written  after 
the  program  itself  was  actually  written.  The  problem  with 
writing  the  documentation  after  the  program  is  completed  is 
that  the  documentation  that  is  supposed  to  aid  in  the  devel- 
opment     and   decision      making      processes      cannot   possibly     be 
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used.  Also   the      documentation   becomes      static    in      nature. 

That  is,  all  the  dynamic  creativi-y  cannot  be  included  in 
the  process  of  documentation  and  all  we  see  is  the  final 
resulting  document.  This  is  very  much  like  a  college 
professor  receiving  a  math  or  physics  exam  with  only  the 
answers   and  no    actual   work    shown. 

Another  idea  for  good  documentation  is  that  the 
specifications  and  standards  should  require  aids  that 
promote     the     understandability        of        the      program.  This 

includes  the  concept  of  providing  comments  in  the  program 
listing,  references  in  the  source  listings  for  certain  soft- 
ware specifications,  and  any  other  references  necessary  to 
trace   through      other     related   documants. 

System  specifications  should  be  designated  as  to  the 
kind  of  information  that  is  to  be  conveyed  to  the  maintainer 
via  documentation.  This  idea  implies  that  certain  types  of 
documentation  convey  certain  kinds  of  information,  and  that 
only  certain  bits  of  information  are  required  for  certain 
maintenance  functions.  The  idea  of  different  kinds  of  docu- 
mentation delivering  various  kinds  of  information,  and  the 
effectiveness  of  the  forms  of  documentation  will  be 
discussed   below. 
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III.     SOFTWARE    IX)  COHEN  TAT  ION 

This  chapter  covers  many  aspects  of  software  documenta- 
tion. Some  background  is  given  on  documentation  in  general, 
including  a  discussion  about  the  purpose  of  documentation. 
The  various  categories  of  documentation  are  explained  based 
on  the  characteristics  of  the  documsntation  and  the  needs  of 
the      user.  Control     and      development        documentation     is 

discussed,  as  is  static  and  dynamic  documentation.  Also  the 
categories  of  implicit  and  explicit  documentation  as  they 
pertain        tc  the        maintenance        role  are        explained. 

Documentation  dependencies  with  regard  to  skill  levels  and 
position  level  of  personnel  on  the  documentation  team  are 
discussed. 

A.       DOCUMENTATION    BACKGHOOHD 

The  primary  purpose  of  documentation  is  to  iapart  knowl- 
edge about  the  system  to  pertinent  personnel  by  trans- 
ferring recorded  information.  Other  than  the  code  itself, 
the  only  source  of  written  information  about  the  program  is 
the  documentation.  Misunderstandings  can  occur  when  our 
informal,  abstract  ideas  are  translated  into  formal, 
concrete  pieces  of  information.  This  information  transfer 
is  accomplished  by  recording  on  various  forms  of  infor- 
mation storing  media.  This  includes  such  methods  as  manu- 
ally recording  facts  on  paper,  or  electronically  placing 
them  in  a  computer  memory.  Thise  various  information 
recordings  become  forms  of  documentation.  The  documentation 
challenge,  then,  is  to  find  a  way  to  ensure  the  unmolested 
receipt  of  iatended  concepts  by  the  documentation  users. 
When    this      challenge    is     met  effectively,        documentation   is 
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considered  to  have  accomplished  its  goal  of  successfully 
conveying  relevant,  information  from  one  person  to  another. 
Chapter  V  discusses  in  mora  detail  the  particular  documenta- 
tion   formats  and   their  relative   effectiveness. 

One  cannot  hope  to  effectively  transfer  knowledge  about 
the  system  by  simply  flooding  the  maintainer  with  all  the 
information  that  can  possibly  be  assembled.  It  is  necessary 
to  distinguish  between  types  of  documentation,  and  discern 
the  type  of  information  that  each  conveys.  Not  all  types  of 
documentation  are  adequate  for  all  types  of  information 
transfer,  and  consequently,  not  good  for  all  types  of  main- 
tenance  chores. 

B.       DOCUHEHTATION   CATEGORIES 

While  the  idea  of  transferring  information  is  clear,  the 
idea  of  what  kind  and  how  much  information  to  transfer  is 
not  so  clear.  The  amount  of  information  to  transfer  is  both 
task  dependent  and  programmer  dependent.  Both  the  mainte- 
nance task  to  be  accomplished  and  the  level  of  expertise  of 
the  maintenance  person  should  be  considered  when  deciding 
upon  the  category  of  documentation  to  be  used.  For  example, 
if  the  documentation  is  to  be  used  by  someone  who  is  vary 
familiar  with  the  system  and  the  type  of  changes  to  be 
applied  to  the  program,  the  documentation  needed  would  be 
of  a  level  that  is  far  less  detailed  than  that  of  someone 
who  had  never  worked  on  the  system  before.  It  would  be 
helpful  to  find  ways  to  categorize  documentation  in  order  to 
gain    an   understanding  of   the   values   of   each. 

1 .      Internal   and    External    Documentation 

One  way  of  categorizing  documentation  is  based  on 
how  the  documentation  itself  is  transported  (internally  or 
externally) .        Internal     documentation   is      the   documentation 
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that  is  carried  along  with  the  code  (perhaps  in  a  separate 
file.  It  is  usually  embedded  in  the  form  of  comments  or 
cross  reference  listings,  and  is  not  executable.  It  is  an 
integral  part  of  the  program,  so  it  is  always  available.  It 
is  easy  to  maintain  because  it  is  as  easy  to  update  as  the 
code  itself.  When  a  software  modification  is  made,  it  is  a 
simple  matter  to  modify  the  internal  documentation.  Because 
of  the  ease  of  update,  internal  documentation  is  considered 
by  programmers  to  be  very  reliable,  and  the  programmers 
have  a  high  level  of  confidence  in  the  currency  and  accuracy 
of   the   internal    documentation. 

External  documentation  is  the  documentation  that 
exists        outside  the     source      code     of  the      program.  This 

includes  such  things  as  data  flow  diagrams,  flow  charts,  and 
any  other  mode  of  recording  program  information  that  is 
not  an  integral  part  of  the  program.  This  type  of  documen- 
tation is  mere  difficult  to  maintain  than  the  internal  docu- 
mentation because  it  usually  exists  in  hard  copy  only,  thus 
pen  and  ink  charges  are  required  for  making  documentation 
modifications.  Because  of  the  difficulty  encountered  in  the 
updating  of  external  documentation,  often  it  is  not  updated 
when  the  system  is  modified.  This  leads  to  a  low  level  of 
trust  ameng  programmers  with  regard  to  the  reliablility  of 
external  documentation.  This  low  level  of  confidence  in  the 
currency  of  external  documentation  is  often  perpetuated  by 
the  feeling  that  there  is  no  reason  to  update  it  since  it  is 
not  current  anyway,  and  even  if  it  is  updated,  it  won't  be 
trusted. 

2.      Dynamic   and    Static    Documentation 

Documentation  can  also  be  considered  to  be  either 
static  or  dynamic  in  nature.  Dynamic  documentation  involves 
the  conveyence  of  ideas  about  the  actual  developmental 
thought  processes.  This  would  include  the  recording  of 
ideas   that    begin      with  the    first   thoughts      in   the    conceptual 
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phase  of  the  life  cycle.  It  also  includes  the  mistakes  made 
and  the  ideas  considered  and  rejected  for  any  reason.  Prior 
mistakes  and  the  reasons  as  to  why  they  were  mistakes  can 
provide  vital  insights  to  the  maintainers  when  new  changes 
are    being  considered. 

The  dynamic  nature  of  the  documentation  comes  from 
the  fact  that  the  entire  decision-making  process  can  be 
actively  recorded  and  transmitted  to  the  receiver  of  the 
documentation.  The  significance  of  this  type  of  documenta- 
tion, then,  is  the  fact  that  later  enhancements  to  the 
program  (remember,  it  is  the  enhancements  that  make  up  the 
biggest  part  of  the  maintenance  workload)  can  be  considered 
in  light  of  original  design  decisions.  Much  redundancy  in 
the  consideration  of  enhancements  stands  to  be  saved  when 
proper   dynamic    documentation  is   used. 

Static  documentation  can  be  considered  to  be  the 
"final      product"    of      the   documentation      process.  It    is      a 

recording  of  the  current  static  state  of  the  program  at  some 
point  in  time,  and  it  does  not  provide  any  indication  of  the 
dynamics  involved  in  the  evolution  of  the  program  reaching 
that    state.  This    type      of   documentation        includes   things 

such  as  a  system  or  program  flow  chart  or  a  rescurce 
diagram.  It  is  this  type  of  documentation  that  conveys  the 
ideas   of   the  program   or  system   itself,    and    how  it    functions. 

It  must  be  realized  that  both  of  these  types  of 
documentation  are  necessary  for  the  proper  transfer  of 
knowledge  from  the  designer  to  the  maintenance  person, 
without  both  types,  either  the  original  thought  "flavor"  of 
the  designer's  intent  is  lost  with  the  passage  of  time,  or 
the  understanding  of  the  processing  of  the  program  is 
lost. 
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3-      Implicit  and   Explicit   Documentation 

Another  categorization  of  documentation  is  the 
notion   of      implicit    and     explicit    documentation.  Explicit 

documentation  can  be  thought  of  as  the  documentation  that,  is 
physically  available,  in  whatever  form  (dynamic  cr  static), 
at  varying  levels  of  detail.  Explicit  documentation  could, 
therefore,  include  documentation  such  as  comments,  manuals, 
and    flew   diagrams. 

Implicit  documentation  is  a  more  subtle  and  abstract 
type  of  documentation.  This  type  of  documentation  consists 
of  the  "essence"  of  a  program  that  is  made  available  by 
consolidating  information  from  one  or  more  forms  of  ei-her 
the      dynamic     or      static  documentation.  This      concepr     of 

implicit  documentation,  then,  involves  a  synergistic  effect 
that  provides  a  high  level  understanding  of  the  system 
without  large  amounts  of  explicit  physical  information 
necessarily  being  accessed.  Implicit  documentation  provides 
the  "Big  Picture"  for  the  receiver  of  the  information  when 
various  amounts  of  physical  documentation  are  assimilated. 
Thus  implicit  documentation  captures  the  concept  of  trans- 
ferring between  individuals  knowledge  that  would  be  diffi- 
cult   to   impart    through   language   or  explicit   documentation. 

It  is  sometimes  very  difficult  to  convey  abstract 
ideas  through  the  use  of  explicit  informational  documenta- 
tion, yet  enough  documentation  (but  not  so  much  as  to  over- 
whelm) must  be  explicitly  available  to  successfully  generate 
the      implicit      documentation      notion.  This      supports     the 

concept   of    minimal    documentation. 

C.       DOCOBENT&TION   DEPENDENCIES 

Yet  another  way  to  categorize  documentation  is  to 
consider  audience-dependent  and  life  cycle  phase-dependent 
documentation   divisions.      It   is      necessary   to   understand  the 
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needs  cf  the  audience  for  which  the  documentation  is 
intended  and  also  the  life-cycle  phase  to  which  the  documen- 
tation is  related.  These  determinations  are  necessary  so 
that  the  documentation  user  who  is  knowledgeable  about,  the 
system  is  not  completely  bogged  down  by  the  effort  of 
trying  tc  sort  through  a  myriad  of  istails  that  have  nothing 
to  do  with  that  particular  maintenance  task,  or  are  super- 
fluous in  the  sense  that  the  user  already  knows  the  neces- 
sary details.  By  the  same  token,  it  is  inefficient  for  a 
person  who  is  not  well  versed  in  certain  aspects  of  the 
project  to  spend  many  hours  searching  through  lots  cf  docu- 
mentation just  to  find  out  something  specific  about  the 
program  on  which  maintenance  is  to  be  conducted.  There 
must  indeed  be  a  balance  between  very  detailed  and  high 
level  documentation.  The  idea  is  that  unnecessary  work  that 
adds  to  the  overhead  of  the  maintenance  task  should  not  be 
given  to  the  maintenance  person.  (More  is  discussed  in 
Chapter  7  about  how  to  access  the  proper  level  of  detail  of 
documentation. ) 

When  considering  audience-dependent  documentation, 
several        factors      must  be   taken      into      account.  These 

factors  include  the  reader's  skill  level  (or  familiarity 
with  the  project),  the  reader's  position  relative  to  the 
maintenance  job,  and  the  particular  type  of  maintenance  to 
be  accomplished.  A  skilled  person  can  be  defined  as  one  who 
understands  basic  organization  programming  policies  or  tech- 
niques. The  skilled  person  often  possesses  the  quality  of 
familiarity   discussed  earlier. 

Different  kinds  of  documentation  are  appropriate  for  the 
different  factors  mentioned  above,  and  in  order  to  run  the 
maintenance  job  effectively,  these  kinds  of  documentation 
are    critical. 
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1 .      Sk ill   Le vel 

In  considering  ths  idea  of  skill  level  far  the  docu- 
mentation user,  the  level  of  documentation  detail  should  be 
of  concern.  The  documentation  should  be  of  sufficient  level 
so  as  to  give  the  user  the  precise  amount  of  detail  neces- 
sary to  carry  out  the  required  maintenance  function.  This 
means  that,  if  the  user  is  skilled,  the  provided  document 
should  not  contain  minutely  detailed  explanations  of  The 
program  if  the  ideas  are  commonly  understood.  On  The  other 
hand,  the  documentation  must  be  an  adequate  level  of  detail 
so  as  to  provide  the  unskilled  person  with  the  needed  amount 
of   system   specifics. 

The  ideas  of  explicit  and  implicit  documentation 
come    into      play    here.  For   the      highly   skilled      user,      the 

amount  of  physically  explicit  documenTation  can  be  small  and 
condensed  in  nature.  The  amount  of  implicit  information 
would  be  large  because  the  skilled  user  can  accept  high 
level  concepts  that  do  not  have  to  be  explicitly  described. 
That  is,  a  highly  skilled  user  :an  make  use  of  implied 
notions,  such  as  the  notion  that  the  data  in  a  certain 
program  goes  Through  a  "sort  and  eliminate"  routine.  Here 
the  explicit  documentation  would  consist  of  the  information 
thaT  the  data  is  sent  to  the  routine,  while  the  implicit 
information  would  be  made  up  of  commonly  understood  details 
of   the   routine    itself. 

As  for  the  unskilled  user  of  the  documentation,  the 
nature  of  the  explicit  and  the  implicit  idea  conveyence 
would  be  quite  different.  The  unskilled  user  would  need 
much  more  explicit  information  to  absorb  the  sane  amount  of 
knowledge  of  the  portion  of  the  program  to  be  maintained. 
The  necessary  explicit  information  would  likely  include  many 
of  the  specific  details  of  the  "sort"  and  "eliminate" 
routines   separately.  If    the      criteria   for     elimination  of 
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certain  data  were  understood  by  ths  unskilled  user  at  -his 
level  of  detail,  then  those  details  would  be  considered  to 
be  implicit  information.  If  those  criteria  were  unknown  to 
the  unskilled  user,  then  the  explicit  documentation  concept 
must  move  down  another  level  of  detail  to  incorporate  these 
details   explicitly.  The    levels      of   detail      are    translated 

continually      from  the  implicit   to      the   explicit   realm   as   the 
need    for   information    detail    (determined      by   the   skill   level) 
moves   down    to   lower    levels. 

Conversely,  as  the  skill  level  of  the  user 
increases,  information  and  details  required  by  the  user  move 
from  the  explicit  to  the  implicit  realm,  thus  allowing 
broader  concepts  to  be  absorbed  by  the  user.  As  more 
implicit  information  is  required  by  the  user,  a  corre- 
sponding lesser  amount  of  explicit  information  (or  documen- 
tation)   is   required. 

The  consequences  of  having  less  explicit  information 
being  required  means  that  less  documentation  (and  conse- 
quently less  overhead)  needs  to  be  sorted  through  in  order 
to  complete  the  maintenance  task.  The  end  result  is  that  as 
skill  level  increases,  less  time  is  required  for  the 
specific  maintenance  task,  and  a  corresponding  maintenance 
efficiency   results. 

2.      Position 

k  look  at  the  idea  of  a  person's  position  with 
regard  to  the  maintenance  effort  is  useful.  In  order  to 
better  understand  how  the  relative  position  of  the  person 
utilizing  the  documentation  affects  documentation  needs, 
first  we  must  know  whether  the  person  is  considered  to  be  a 
maintainer,    a  manager,    or  a    user. 
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a.  Maintainer 

The  maintainer  is  defined  to  be  the  person  who 
is  actively  involved  in  the  actual  act  of  maintaining  the 
program.  The      maintainer      requires    the      lowest      level      of 

abstraction  of  documentation,  or  the  most  detailed  level  of 
information  because  of  the  actual  physical  maintenance  that 
is  accomplished.  The  type  of  docuaentation  required  by  the 
maintainer  t3  successfully  complete  the  maintenance  task 
then  will  be  on  a  level  that  is  fairly  detailed.  The  depth 
of  detail  required  will  of  course  be  dependent  upon  the 
maintainer' s  skill  level  or  familiarity  as  discussed 
earlier.  The  documentation  type  will  be  of  the  kind  that 
will  promote  the  detail  necessary  ts  complete  the  job.  The 
amount  of  explicit  documentation  will  also  be  determined  by 
skill    level   and    familiarity. 

As  far  as  dynamic  documentation  is  concerned, 
the  maintainer  relies  less  heavily  on  this  level  of  documen- 
tation than  on  the  static  documentation.  The  maintainer  is 
very  concerned  about  the  present  state  of  the  program 
because  the  present  state  is  what  is  to  be  modified.  The 
decision  as  to  whether  or  not  to  make  the  modification  is 
usually  made  at  a  higher  level,  and  thus  the  dynamic  docu- 
mentation will  be  better  used  at  that  higher  level  (probably 
the    manager   level)  . 

b.  Manager 

The  manager  category  can  be  defined  so  as  to 
include  anyone  who  is  directly  connected  with  the  mainte- 
nance of  the  system,  but  not  actively  involved  with  the 
actual  physical  maintenance  of  the  project.  This  could 
include  the  maintenance  team  leader  in  the  supervisory  role, 
the  department  head,  or  higher  level  decision  makers.  The 
type  of  documentation  that  the  manager   needs  should  be  of  a 
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much  higher  level  of  abstraction  requiring  less  derail  than 
that  required  by  the  maintainer.  This  means  that  much  more 
documentation  of  an  implicit  nature  is  acceptable  in  order 
to      meet   the     needs   of      the    manager      level    personnel.  The 

greater  the  amount  of  implicit  documentation  needed,  the 
less  the  amount  of  explicit  documentation  necessary. 
Likewise,  the  less  the  detail  level  of  the  explicit  documen- 
tation, the  less  the  amount  of  details  through  which  the 
manager   must  sort.  The   smaller   anount    of      detail   required 

leads   to   the  saving    of  time      and    money. 

The  manager  could  very  well  be  the  biggest  user 
of  dynamic  documentation.  The  manager  at  the  maintenance 
group  supervisor  level  is  likely  to  be  the  one  who  must  look 
at  the  way  prior  decisions  were  made  in  order  tc  verify  the 
practicality     of  requested      maintenance   enhancements.  The 

manager  might  want  to  avoid  re-deciding  something  that  is 
already  a  given  and  has  been  recorded  in  the  dynamic 
dccumentaticn. 

The  manager  could  also  be  a  very  heavy  user  of 
static  documentation  in  the  sense  that  it  might  be  necessary 
to  reference  the  present  status  of  the  maintenance  effort  in 
order   to      properly    set   up      the   maintenance   team.  Thus   the 

manager  must  rely  heavily  on  the  static  documentation  tc 
understand  the  program  status  after  design  and  also  to 
modify  the  existing  documentation  as  the  program  is  modi- 
fied. This  also  implies  that  dynamic  documentation  by  the 
maintenance  team  is  occurring  along  with  program  modifica- 
tions, and  the  manager  is  responsible  for  updating  or 
creating  the  appropriate   dynamic   documentation. 

c.      User 

The  user  is  anyone  who  actually  uses  the  system 
(the  pilot  using  an  avionics  system,  a  fire  control  techni- 
cian   on    board  ship,    etc.)         The  usee    might    be   someone   who   is 
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considering  purchasing  services  or  products  from  the  company 
and  is  interested  in  the  stability  of  the  company  as  a 
whole.  The  system  is  a  vital  part  of  the  company,  and 
consequently  the  user  might  be  interested  in  the  program  or 
system  frcm  a  very  abstract  point  of  view.  Other  than 
specific  user's  manuals  and  system  operational  guides,  the 
user  needs  little  or  no  detailed  information  and  can 
tolerate  a  large  amount  of  implicit  documentation.  The 
amount  of  explicit  documentation  required  for  the  user  will 
be  very  small  indeed,  perhaps  even  a  simple  listing  of  the 
systems  cr  programs  available  to  the  company.  The  user 
simply  wants  to  know  what  capabilities  are  present  and  if 
they      meet      the      user's     needs.  Any      further      detail     is 

superfluous. 

The  user  is  probably  not  interested  in  any 
dynamic  documentation  and  has  vary  little  interest  in 
static   documentation-  He    does   not      really   care      about   the 

design  decisions  that  occurred  during  the  development  of  the 
system,  but  merely  about  the  fact  that  there  exists  a 
system   sufficient   for  his      needs. 

D.       ROLE    OF    DOCUMENTATION 

The  idea  of  implicit  and  explicit  information  can  be 
utilized  here.  Returning  for  a  moment  to  the  example  in  the 
last  chapter  concerning  the  likening  of  the  receipt  of  one 
final  piece  of  documentation  to  that  of  a  college  professor 
receiving  only  the  answers  on  a  physics  or  math  test  without 
explanation  as  to  how  the  answers  came  about,  more 
discussion  is  in  order.  The  dynamic  nature  of  showing  the 
work,  whether  the  work  was  on  an  exam  or  on  a  program,  helps 
both  the  programmer  and  the  maintenance  person  (cr  the 
student  and  the  professor)  follow  the  design  and  development 
of      ideas.  Since    documentation,         as      described      earlier, 
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involves  the  transfer  of  ideas,  it  is  crucial  thai  these 
ideas  be  transferred  dynamically  in  the  form  of  progressiva 
documentation.  It  is  difficult  to  understand  the  thought  and 
development  process  that  goes  into  a  problem  when  all  -hat 
is  seen  by  the  receiver  of  the  information  is  the  final 
solution. 

We  need  not  worry  that  the  final  documentation  product 
might  contain  some  recording  of  our  initial  erroneous 
efforts.  In  fact  it  might  be  helpful  to  the  maintainer  if 
the  initial  trial  and  error  efforts  were  made  available. 
It  could  save  the  maintenance  person  the  redundant  effort  of 
trying  to  rethink  the  designer's  ideas  in  order  to  possibly 
change   a   previous   logical  decision. 

The  complete  documentation  could  also  keep  the  main- 
tainer from  overlooking  some  critical  piece  of  information 
that  would  make  the  newly  proposed  enhancement  an  obviously 
bad    move.  Another    advantage     of   documenting     the   creative 

process  is  that  ideas  that  were  not  feasible  (technologic- 
ally or  environmentally)  at  the  time  of  design,  and  conse- 
quently rejected,  could  be  used  during  the  maintenance  phase 
as  a  result  of  system  requirement  changes  or  technological 
advances. 

Ideally,  then,  the  maintainer  will  not  receive  as  docu- 
mentation something  as  simple  as  the  statement  that  a 
system  will  use  red  ribbons  for  printed  output.  This  gives 
no  indication  as  to  how  much  thought,  if  any,  went  into  the 
decision.  When  the  suggestion  for  an  enhancement  to  allow  a 
different  color  for  printed  output,  the  maintenance  person 
must  try  to  second  guess  the'  designer's  decision  as  to  why 
red  was  selected,  and  if  another  color  is  possible.  If  this 
knowledge  were  made  readily  available,  the  maintainer  could 
possibly  head  off  an  expensive  analysis  of  colored  printed 
outputs  that  would  discover  that  the  designer  already  knew 
that  red  printouts  were  the  only  ones  that  could  be  read 
under   the   special  lighting    needed   for   a   security    project. 
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IV.     DOCUMENTATION    HIERARCHY 

The  idea  of  a  documentation  hierarchy  is  introduced 
along  with  an  explanation  of  the  proper  use  of  the  hierarch- 
ical organization  and  how  it  promotes  the  concapt  of 
minimal  documentation.  System  and  program  documentation  are 
discussed  in  detail  as  they  relate  to  both  the  system  hier- 
archy  and  the   maintenance   task. 

A.       SYSTEM    DOCUMENTATION    HIERARCHY 

One  prcblem  -chat  faces  the  manager  is  how  to  wada 
through  all  available  docu mentation  in  order  to  glean  out 
the  pertinent  information  for  the  present  task  without 
getting  togged  down  with  a  massive  volume  of  material.  The 
same  problem  is  faced  by  the  maintainer  who  may  not  need  to 
know  all  the  system  design  information  when  the  task  at  hand 
(as  determined  already  by  the  managerial  decision-making 
process)  is  simply  to  modify  a  small  section  of  code.  It  is 
clearly  wasteful  in  this  case  to  force  the  maintainer  to 
sort  through  huge  amounts  of  irrelavant  material  concerning 
high  level  system  information  just  to  locate  information 
pertaining   to  the   immediate    code    modification   task. 

The  user  reguires  information  about  the  system  on  a  high 
conceptual  level,  but  the  deluge  of  unorganized  documenta- 
tion with  all  levels  of  detail  would  require  time  consuming 
searching,  and  most  of  the  detailed  information  would  be 
utterly   useless. 

A  solution  to  the  problem  of  unorganized  levels  of 
detail  in  documentation  is  to  construct  an  organized  hier- 
archical structure  for  the  various  forms  of  documentation 
based   on   the  level   of  detail.        This    documentation    hierarchy 


40 


can  provide  precisely  the  appropriate  level  of  detail  in  the 
available  dccumentati.cn  for  the  receiver,  regardless  of 
whether  the  receiver  is  the  user,  manager,  or  maintainer. 
Figure  4.1  provides  an  example  of  a  system  documentation 
hierarchy  organization  that  indicates  the  various  levels  of 
detail   involved    in    the   documentation    of   a   system. 

All  of  the  documentation  is  available  to  the  proper 
receiver  in  a  concise  format  that  gives  the  receiver  the 
least  amount  of  detail  necessary  (thus  promoting  the  concept 
of    minimal      documentation  as      mentioned    earlier).  As   more 

detail  is  needed,  more  explicit  documentation  is  accessible. 
This  promotes  under standabi lit y  and  contributes  to  an  effi- 
cient   maintenance  effort. 

The  system  documentation  hierarchy  of  Figure  4.1  shews 
arrows  -hat  indicate  a  downward  and  upward  flow  of  documen- 
tation access.  As  progress  is  made  down  to  lower  levels  on 
Figure  4.1,  more  detail  is  attained  in  the  documentation. 
Conversely,  as  movement  is  made  up  the  levels,  less  detailed 
descriptions  and   larger   concepts   are    accessed. 

B.       SYSTEM    DOCUMENTATION 

To  understand  more  about  the  system  documentation  hier- 
archy, it  must  be  understood  what  is  meant  by  system  docu- 
mentation. A  system  can  be  defined  as  one  or  more  programs 
that  work  in  conjunction  to  perform  a  particular  function. 
The  system  can  be  very  simplistic,  such  as  a  simple  vote 
counting  system,  or  it  can  be  very  complicated  as  in  the 
case  of  a  sophisticated  weapons  system.  Since  a  system  has 
been  defined  as  the  combination  of  one  or  more  programs  that 
perform  a  function,  system  documentation  is  defined  as  the 
documentation  of  the  overall  system  life  cycle  from  the 
project   conception    phase  through   the    support    phase. 
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Figurs  4,1    System  Documentation  Hierarchy. 
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System  document ation  contains  recorded  information 
pertaining  to  the  complete  description  of  the  evolution  of  a 
system   throughout   its   life    cycle.  It    includes    a    record    of 

the  development  process  and  the  maintenance  history  in 
either  implicit  or  explicit  form.  System  documentation 
contains  both  dynamic  and  static  information  and  can  be 
used      by  maintainer,        manager,      and      user    personnel.  The 

specific  form  of  documentation  is  dependent  upon  the 
requirements  of  the  task  to  be  accomplished  and  the  needs  of 
the    receiver. 

Since  a  system  is  made  up  of  one  or  more  programs, 
program  documentation  is  considered  to  be  included  as  a  part 
of  the  system  documentation.  In  Figure  4. 1  program  documen- 
tation consists  of  levels  3  and  4.  Both  system  and  program 
documentation  are  discussed  in  greater  detail  later  in  -his 
chapter. 

1 .      Lev el   J, 

The  overall  system  documentation  follows  a  hierarch- 
ical structure  with  varying  levels  of  detail  as  shown  in 
Figure      4.1.  The      highest    level     of      abstraction    for      the 

system,  level  1,  includes  a  narrative  description  of  the 
system  itself  and  a  description  of  the  system  environment 
along   with   any    assumptions    about   the    system.  The   environ- 

mental description  would  include  information  pertaining  to 
the      system     hardware     and        software      environments.  This 

includes  system  restrictions  and  limitations  that  might 
result  from  certain  hardware  or  software  constraints  under 
which  the  system  must  operate.  Military  applications  such 
as  an  avionics  system  or  a  submarine  weapons  system  would 
dictate  specific  environmental  restrictions  because  of  the 
very    nature   of    the   system  activities. 

It  is  in  this  level  that  the  documentation 
contains      the      most    abstract   information   about     the    project. 
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This  level  of  detail  would  probably  be  most  often  used  by 
the  user  personnel,  but  this  non-3etailed  narrative  level 
could  also  be  of  use  to  the  manager  and  maintenance 
personnel  who  require  an  overall  understanding  of  the 
system. 

2.      Level   2 

Level  2  is  the  next  level  of  abstraction  in  the 
hierarchical  structure  and  contains  slightly  more  derail 
than  level  1.  This  level  includes  any  system  flow  informa- 
tion, such  as  perhaps  system  flow  diagrams,  and  system  input 
and  output  descriptions.  The  inter-program  module  descrip- 
tions are  included  in  this  level;  this  level  gives  informa- 
tion about  how  individual  programs  are  inter-related  in  the 
system.  This  type  of  information  can  be  conveyed  with  the 
use    of   narrative   remarks. 

Since  level  2  system  documeatation  includes  informa- 
tion such  as  system  input  and  output  specifications  and 
requirements,  maintainers  and  managers  find  this  input/ 
output  information  to  be  valuable  because  they  must  ensure 
that  the  maintenance  of  the  program  is  accomplished  in  such 
a  way  that  the  output  requirements  are  correctly  attained 
when    the   appropriate   system    inputs  are   given. 

Managers  need  to  know  the  system  input  and  output 
specifications  that  fit  user  needs  in  order  to  ensure  main- 
tainers have  the  proper  information  as  translated  from  the 
user  (who  very  likely  is  not  as  technically  oriented  as  the 
manager  or  tha  maintainer)  requirements.  Thus  the  managers 
can  take  the  user  input  and  output  requirements  as  requested 
by  the  users  and  translate  them  into  an  understanding 
between  the  maintainers  and  the  users  in  order  that  effec- 
tive   maintenance   can   be   accomplished. 

Users  obviously  play  an  important  role  in  the  gener- 
ation  of   the     general  input    and   output      specifications,      and 
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these  specifications  must  make  sense  to  the  managers  before 
the  maintainers  can  be  expected  to  understand  and  perform 
maintenance     tasks.  An  understanding      between      users      and 

managers  must  therefore  be  reached  as  to  what  the  users  want 
(or  think  they  want)  .  The  prudent  user  will  heed  management 
advice   when   cDnsidering   reasonable   input   and   output    formats. 

System  logic  information  is  also  a  part  of  level  2 
of  the  system  documentation  hierarchy,  and  it  conveys  the 
logical  flow  of  the  project.  This  logical  information  could 
include  a  narrative  section  that  describes  the  purpose  of 
the  system  and  how  it  is  logically  constructed.  The  hier- 
archy of  programs,  functions,  and  modules  can  be  described 
in  the  narrative.  The  system  flow  documentation  concerning 
the  relationship  of  the  individual  modules  can  take  the 
form  of  system  flow  charts  or  flow  diagrams  with  accompa- 
nying  comments. 

The  inter- program  module  descriptions  provide  infor- 
mation about  the  relationship  of  the  programs  to  the  system 
and     "to    each     other.  Any      restrictive   characteristics     or 

program  environmental  considerations  are  included  in  the 
inter-module  narrative. 

The  rest  of  the  lower  levels  of  abstraction  make  up 
the  program  documentation  portion  of  the  documentation  hier- 
archy. It  is  in  these  levels  that  the  degree  of  detail  is 
such  that  the  system  is  no  longer  the  focal  point  of  the 
documentation,  and  the  program  specifics  are  brought  into 
view . 

C.        PBOGRAH    DOCUMENTATION 

Program  documentation,  as  indicated  above,  consists  of 
the  recorded  information  about  the  program  itself.  It  is  of 
a  more  detailed  nature  than  the  system  documentation  and  is 
most    useful     for   the   manager      and   maintainer.  It   contains 
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information  pertaining  to  program  module  construction  and 
logic  flow.  Data  structure,  data  flow,  and  control  flow 
specifics  are  recorded  so  that  the  documentation  receiver 
has      relevant   program     information  available.  Programming 

methodology  techniques  and  maintenance  history  become  part 
of  the  program  documentation  as  well.  Dynamic  documentation 
describing  inter-module  concepts  and  structures  is  included, 
but  static  documentation  makes  up  the  bulk  of  the  program 
documentation.  Specific  explicit  forms  of  program  documen- 
tation include  flow  charts,  English  narrative  statements, 
resource   diagrams,    and  Petri  nets. 

While  all  of  the  levels  in  Figure  4.1  represent  system 
documentation,  levels  3  and  4  can  be  combined  to  make  up  the 
program  documentation  portion  of  the  system  documentation 
hierarchy. 

1.      Level    3 

Level  3  of  Figure  4. 1  is  the  first  level  of  the 
program  documentation  and  conveys  a  particular  program 
description.  Particular  program  constraints  that  deal  with 
specific  programs  are  described  in  Level  3  along  with  any 
high  level  narrative  about  the  program  itself.  Level  3  does 
not  contain  any  inter-program  relationships  with  other 
programs.  It  is  the  level  that  deals  with  strictly  a  single 
program. 

This  level  of  abstraction  is  more  detailed  than 
levels  1  and  2,  and  is  very  useful  to  both  the  manager  and 
the  maintainer.  The  manager  needs  to  keep  the  high  level 
program  concept  so  that  the  maintainers  can  be  properly 
managed  without  forcing  the  maintainers  to  be  concerned  with 
any    unneccessary      abstract    information.  The  manager      must 

keep  the  program  concept  in  mind  and  relate  it  to  the  rest 
of   the   system    (level    2  and    higher) . 
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The  maintainor  can,  however,  use  this  level  of 
detail  to  aid  in  the  understanding  of  how  a  particular  main- 
tenance task  is  constrained.  The  manager  is  responsible  for 
the  overseeing  of  the  inter-program  module  relationships, 
but  a  knowledgeable  maintenance  person  can  be  of 
immeasurable  aid  to    the   wise  manager    in    this   area. 

2.      Level   4 

The  next  lower  level  of  abstraction,  level  4, 
provides  the  greatest  level  of  detail.  This  isvel  is  used 
very  heavily  by  maintenance  personnel,  and  often  by  manage- 
rial personnel.  This  level  consists  of  very  detailed 
descriptions  such  as  program  flow  information  and  input/ 
output  formats.  Much  of  this  documanta tion  is  vary  explicit 
in  nature.  It  can  be  static  or  dynamic.  Flowcharts, 
inter-code  comments,  logic,  and  data  flow  diagrams  are 
included  in  this  level  of  documentation.  It  is  this  level 
of  detail  that  describes  program  modules  in  enough  detail  so 
as   to    promote  understandabi lity  among   maintainers. 

While  maintainers  are  the  heaviest  users  of  program 
documentation,  and  users  are  the  primary  users  of  the  higher 
level  system  documentation,  managers  must  bridge  -he  gap 
between  the  two  levels  of  documentation.  Managers  are 
involved  with  high  level  decisions  that  require  an  overall 
system  understanding,  yet  they  must  also  be  involved  with 
some  of  the  lower  levels  of  program  documentation  in  order 
to   properly   manage    the   maintenance   functions. 

D.       DOCOHEHTATIOH   HIEBAHCHI    UTILIZATION 

The  documentation  hierarchy  is  set  up  so  that  anyone  can 
access  the  hierarchy  at  any  of  the  indicated  levels,  and 
thus  te  exposed  to  the  level  of  detail  characteristic  of 
that    particular    level.      If    more   detail   is   needed    for   a    given 
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task,  then  a  simple  move  down  to  the  next  level  for  greater 
derail  is  permitted.  By  the  same  token  if  it  is  determined 
that  the  level  accessed  is  too  detailed  for  the  particular 
needs  of  the  person  using  the  documentation,  then  the  arrow 
is  simply  followed  up  to  a  higher  level  of  abstraction  that 
meets   the   desired  needs. 

Each  form  of  documentation,  than,  is  catalogued  as  to 
its  detail  level,  and  a  menu  format  (either  paper  or  elec- 
tronic)   can   be    utilized  to    directly   access   the  level   needed. 

With  the  capability  of  moving  either  direction  in  the 
hierarchy  structure,  great  flexability  is  built  into  the 
system,  and  only  the  exact  amount  of  documentation  needed  is 
accessed.  This  promotes  the  minimal  documentation  concept 
and,  therefore,  keeps  the  documentation  overhead  down  to  a 
minimum.  The  amount  of  useless  information  that  must  be 
waded  through  in  order  to  find  the  proper  documentation  is 
kept  lew  as  a  result  cf  proper  utilization  of  the  documenta- 
tion   hierarchy    concept. 
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v-    HUn  AT  ION    OF    FORMS    OF    DOCUMENTATION 

Chapter  III  discusses  the  various  types  of  documentation 
and  how  they  relate  to  the  maintenance  effort.  It  is  impor- 
tant to  carry  the  documentation  discussion  further  and  talk 
about  not  only  the  types  of  documentation  that  are  useful, 
but  also  some  specifics  as  far  as  physical  arrangements  are 
concerned.  The  discussion  will  focus  on  explicit  types  of 
program  document  at ion,  and  how  soma  of  the  physical  charac- 
teristics of  the  documentation  affect  the  efficiency  of 
maintenance   performance. 

A.       EVALUATION    EXPERIMENTS 

When  dealing  specifically  with  programming  documentation 
(levels  3  and  4  of  Figure  4.1)  which  is  most  often  used  by 
maintainers,  it  would  be  helpful  to  understand  which 
different  forms  of  documentation  are  most  effective. 
Chapter  III  discusses  the  different  types  of  information 
utilized  by  users,  managers,  and  maintainers,  depending  on 
the  maintenance  task  and  the  documentation  receiver.  This 
chapter  discusses  some  specific  forms  of  documentation  and 
how  effective  they  can  be  in  promoting  understandability  for 
efficient   program   maintenance. 

It  has  been  determined  by  Ganeral  Electric  studies 
(Ref.  10]  that  the  best  form  of  documentation  to  be  used  for 
maintenance  is  heavily  dependent  on  the  type  of  program 
processing  that  takes  place,  in  particular  whether  it  is 
sequential   or   concurrent  processing. 
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1 .      Documentation  for   Sequential    Processing 

In  determining  the  most  eff active  type  of  documenta- 
tion format  for  sequential  processing,  a  primary  concern 
must  involve  the  type  of  symbology  used  to  present  the 
information.  It  would  be  beneficial  to  ascertain  the  best 
form  of  symbology  as  seen  by  the  maintenance  personnel  in 
terms  of   maintenance   efficiency. 

The  three  symbology  types  used  in  the  General 
Electric  Studies  consist  of  narrative  Englist  text,  an 
abbreviated  program-like  language  called  Program  Design 
Language       (PDL) ,      and     ideograms.  The      narrative    text     is 

frequently  embedded  in  the  source  coda  as  either  global  or 
in-line   comments.  The   PDL   is      succinct    and     uses    strictly 

defined  keywords  to  describe  arguments  or  predicates. 
Ideograms  are  often  found  in  flow  charts  and  HIPO  charts. 
Sets  of  ideograms  represent  processes  in  a  program 
[Bef.    11]. 

Another  primary  concern  which  must  be  dealt  with 
when  weighing  effective  documentation  is  the  issue  of 
spatial   arrangement.  Spatial  arrangements     can    aid      main- 

tainers  in  understanding  the  flow  of  control  in  a  sequential 
program,  and  it  would  be  helpful  if  the  best  spatial  format 
could  be  determined.  The  spatial  arrangements  provide 
different  ways  of  representing  control  flow  and  nesting 
levels.  The  spatial  arrangements  used  in  the  experiments 
are    sequential,    branching,    and    hierarchical   representations. 

The  sequential  arrangement  represents  both  the 
control  flow  and  the  levels  of  nesting  in  a  vertical  manner. 
The  branching  arrangement  presents  the  flow  of  control  in  a 
vertical  manner  while  the  nesting  lavels  are  presented  hori- 
zontally. Finally,  in  the  hierarchical  arrangement,  the 
control  flew  is  represented  horizontally  and  the  nesting 
levels  are   presented    vertically. 
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The  sequential  processing  experiments  were  designed 
to  run  the  gamut  of  many  of  the  maintenance  tasks  performed 
by  programmers.  The  tasks  included  answering  questions 
about  prcgram  coding,  program  debugging,  program  modifica- 
tion, and  program  operation.  The  maintenance  tasks  were  to 
be  completed  using  the  various  foras  of  documentation  being 
tested.  The      studies      were      conducted      with      professional 

programmers  who  were  asked  to  answer  questions  about 
programs.  The  programmers  were  allowed  to  reference  only 
the  various  forms  of  documentation  having  the  spatial  and 
symbology  characteristics  mentioned  above  to  get  information 
about    the   programs. 

Nine  specification  formats  were  presented  to  the 
programmers  for  their  use  in  the  experiments.  Each  of  the 
three  types  of  symbology  was  presented  in  each  of  the  three 
spatial   arrangements. 

The  participants  were  also  asked  to  choose  which 
format  of  documentation  they  found  to  be  the  easiest  to  use. 
This  choice  was  then  weighed  against  the  type  of  documenta- 
tion that  produced  the  best  results  in  terms  of  maintenance 
effectiveness. 

In  the  first  experiment,  the  programmers  were  asked 
to  answer  backward  and  forward-tracing  questions  and  input/ 
output  questions  about  the  program  using  the  test  documenta- 
tion   provided. 

The  results  showed  that  the  sequential  PDL,"  the 
branching  PDL,  and  the  branching  ideogram  versions  of  docu- 
mentation were  the  most  effective  for  answering  the  tracing 
questions. 

For  the  input/output  questions,  no  significant 
differences  were  found  between  the  forms  of  documentation. 
The  most  preferred  combinations  of  documentation  formats 
were  the  PDL  symbology  and  the  branching  spatial  arrange- 
ments [Ref-    11  ]. 
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In  another  experiment  programmers  wars  asked  to 
complete  the  coding  of  portions  of  programs  referencing  only 
the  documentation  under  test.  In  this  experiment  the 
English  narrative  format  took  significantly  longer  to 
produce  cede  than  did  the  PDL  format.  The  English  version 
also  produced  the  largest  number  of  errors,  while  the  PDL 
produced  the  smallest. 

The  spatial  arrangement  effects  were  not  signifi- 
cant, tut  the  formats  of  the  sequential  PDL  and  the 
branching  PDL  arrangements  produced  the  best  experimental 
results.  The      sequential      English      version      produced      the 

poorest   performance. 

The  programmers  also  chose  the  PDL  branching 
arrangements  as    the    preferred    format    combination. 

In  yet  another  experiment  the  programmers  had  to 
correct  error-seeded  programs,  again  utilizing  only  the 
documentation   under    test   as   a    source    of    program   information. 

.The  best  results  in  performance  occurred  with  the 
PDL      and   ideogram      symbolcgies      for      this   experiment.  The 

spatial  effects  were  again  not  significant.  The  sequential 
and  branching  PDL  formats  proved  to  be  high  performers,  as 
did    the    branching  and  hierarchical   ideograms. 

The  programmers  had  no  preference  for  the  type  of 
symbology  in  this  experiment,  bat  they  did  prefer  the 
branching   spatial  arrangement   (Ref.    13]. 

Though  slightly  different  results  were  produced  in 
this  experiment  depending  on  the  maintenance  task,  overall 
the  indication  is  that  performance  is  improved  when  the 
symbology  is  of  a  succinct  nature,  such  as  in  the  PDL 
format.  The  English  narrative  proved  to  be  too  wordy  and 
awkward  to  provide  efficiency  when  attempting  software 
maintenance. 

As  for  the  spatial  arrangement  issue,  the  best 
overall  performance  resulted  from  the  use  of  a  branching 
arrangement     in    providing      the  clearest      display   of     control 
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flow.         The  PDL    branching  format,        than,  seemed    to   promote 

understandability   for  the  m aintainer,      and  the  PDL    branching 

format  was  selected  by  the  programmers  as  the  easiest 
overall    format    to   use. 

2.      Documentation  for   Concurrent    Processing 

Since  much  of  today* s  program  processing  is  concur- 
rent, it  is  wise  to  investigate  documentation  effectiveness 
for      the        concurrent     realm      of        processing.  Concurrent 

processing  of  programs  entails  two  or  more  portions  of  the 
program  executing  si amltaneously .  Because  of  the  complexity 
involved  with  concurrent  processes,  programs  that  contain 
concurrent  processing  must  be  carefully  documented.  It  is 
important  to  convey  information  about  the  control  flow  of 
the    program  and    the    sharing    of   resources. 

The  formats  of  documentation  used  for  the  General 
Electric  studies  of  concurrent  processing  documentation 
[Ref.  14]  consist  of  three  types:  PDL;  resource  diagrams; 
and  Petri  nets.  The  first  form  of  documentation  is  the  same 
PDL    as      used  in    the      sequential   processing   tests.  The   PDL 

emphasizes    the    control-flow    charactaristics   of  the    program. 

The  second  form  of  documentation,  the  resource 
diagram,  places  emphasis  on  the  concept  of  providing 
resource     sharing     information      to        the      programmer.  The 

resource  diagram  uses  communication  circles  containing 
abbreviated  English  statements  to  oonvey  information  about 
the  relationships  between  processes.  Natural  English  state- 
ments provide  narrative  information  contained  in  process 
boxes  to  describe  the  process  itself.  Resource  diagrams  are 
arranged  spatially  in  a  branching  format  similar  to  the 
branching  organization  used   in  the   sequential  experiments. 

The  third  form  cf  documentation  is  that  of  a  Petri 
net.  Petri  nets  have  nodes  that  oontain  information  that 
indicates      resource        usage      for        required      tasks,  while 
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control-flow  information  is  conveyed  with  a  constrained 
language  description.  The  Petri  net  format  of  documentation 
places  equal  emphasis  on  control-flow  and  resource  sharing 
information.  The  spatial  arrangement  of  the  Petri  net  is 
also    similar  to    that   of   a  branching   organization. 

In  the  concurrent  processing  experiment  programmers 
were  asked  to  make  either  data-structure  or  control-flow 
modifications  to  each  of  three  programs.  For  both  types  of 
modifications,  the  resource  diagrams  proved  to  be  the  best 
performers.      The   Petri  net    gave   the   poorest   performance. 

Since  the  resource  diagrams  emphasize  information 
about  the  resource-sharing  aspect  of  the  processing  of  the 
program,  it  is  interesting  to  note  that  the  control-flow 
information  that  was  so  important  for  the  sequential 
processing  of  a  program  is  not  as  vital  for  the  maintenance 
of   concurrent   processes. 

When  asked  to  select  the  documentation  format  that 
was  easiest  to  use,  the  PDL  format  »as  selected.  It  turned 
out,  however,  that  the  most  efficient  form  of  dDcumentation 
for    the   concurrent    processing   was   the   resource  diagram. 

B.       DISCUSSION 

The  results  of  the  experiments  yield  some  ideas  that  can 
be-  incorporated  into  explicit  documentation  types  for 
program    documentation.  With    proper      incorporation   of      the 

ideas,  understandabilit y  can  be  enhanced  for  maintainers 
resulting  in  a  .positive  influence  on  maintenance 
efficiency. 

When  determining  the  type  of  documentation  to  be 
accessed  in  the  documentation  hierarchy  of  Figure  U. 1  in 
Chapter  III,  it  is  important  to  realize  that  there  is  not 
one  "best"  form  of  documentation  for  all  maintenance  tasks. 
The    type   of     processing    (sequential   or   concurrent)         must   be 
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taken  into  account  when  identifying  the  bes-  documentation 
format  tic  include  in  the  hierarchy.  This  processing  infor- 
mation is  provided  in  a  narrative  ssnse  in  level  3.  Level  4 
will  provide  the  actual  flew  information,  be  it  resource- 
flow    or    control-flow    information. 

The  General  Electric  studies  show  support  for  the 
concept  of  minimal  documentation  introduced  in  chapter  II. 
The  English  narratives  were  found  to  ba  too  long  and  awkward 
for  the  best  performance  of  maintenance.  When  the  method  of 
transferring  information  took  on  the  more  abbreviated  form 
of  the  PDLf  maintainers  showed  a  preference  for  this  forma- 
of  symbology  presentation.  This  preference  held  true  for 
both  the  sequential  and  the  concurrent  programming  techni- 
ques. The  implication  is  that,  even  though  the  ideas 
conveyed  in  both  the  formal  English  narrative  and  the  PDL 
were  the  same,  the  programmers  chose  the  succinct  method  of 
symbology  as  being  easier  to  glean  the  necessary  informa- 
tion for  the  maintenance  task.  A  significant  point  is  that 
the  programmers  chose  not  tc  wade  through  all  the  super- 
fluous language  provided  by  the  English  narrative,  thus 
indicating  a  preference  for  minimal  documentation.  As  far 
as  sequential  processing  is  concerned,  the  PDL  proved  to 
be  not  only  the  programmers  choice  for  symbology  represen- 
tation, it  also  proved  to  be  the  most  efficient.  In  the 
case  of  the  concurrent  processing,  the  PDL  was  the  preferred 
method  of  symbology  representation,  but  the  resource  diagram 
proved  to   be  more  efficient. 

The  concept  of  minimal  documentation  is  not  contradicted 
by  -he  fact  that  the  PDL  form  of  symbology  was  preferred  by 
programmers,  but  resource  diagrams  proved  to  be  the  most. 
efficient  for  maintenance  purposes  in  concurrent  program- 
ming. The  fact  is  that  the  information  required  for  concur- 
rent processing  maintenance  is  simply  different  than  the 
information     that      is     provided      by      the      PDL.  Concurrent 
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processing  requires  information  with  emphasis  on  the 
resource-sharing  aspect  of  the  program,  while  the  ?DL 
provides  information  primarily  concerning  the  aspecr.  of 
ccntrol-flow  (which  is  of  primary  concern  in  the  sequential 
processing  program) .  In  this  experiment  it  turned  out  that 
the  actual  minimal  documentation  was  the  resource  diagram, 
and    not   the   PDL    the    maintainers   preferred. 

When  determining  which  format  of  documentation  to  access 
for  the  performance  of  maintenance,  the  format  which  best 
suits  the  task  at  hand  should  be  considered  in  the  selection 
process  with  emphasis  on  maintenance  efficiency.  When  the 
proper  level  (or  levels)  of  documentation  are  selected  from 
the  documentation  hierarchy,  along  with  the  best  physical 
representation  of  the  documentation,  then  minimal  documenta- 
tion is  accessed  and  effective  understandability  is 
achieved.  The  end  result  is  an  effective  and  efficient 
performance   of    the    maintenance   task. 
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VI.     CONCLUSIONS     AND    3 ECO M MSN  DAT IONS 

Since  m air. te nance  costs  make  up  the  largest  part  of  most 
software  projects,  it  is  vital  to  find  effective  ways  to 
reduce  cr  make  more  efficient  tie  software  maintenance 
effort.  When  good  documentation  techniques  are  incorporated 
into  the  project  evolution,  then  development  ideas  and  other 
relevart  information  about  the  system  can  be  successfully 
recorded  and  transferred   to    other   individuals. 

Since  it  is  critical  that  good  documentation  techniques 
be  emphasized,  accurately  determining  the  precise  type  and 
amount  of  documentation  for  software  maintenance  is  vital. 
Minimal  documentation  is  the  result  of  that  determination 
and  should,  therefore,  be  incorporated  into  software 
projects   where    appropriate.  (Some      programs   are    simply   not 

maintained   and      therefore  do      not   need      maintenance   oriented 
documentation. ) 

Managers  of  the  maintenance  team  often  have  misconcep- 
tions about  how  the  time  spent  :n  software  maintenance 
should  be  allocated.  Because  of  these  misconceptions,  a 
closer  look  at  how  maintenance  time  is  spent  is  in  order. 
Perhaps  an  analysis  of  the  maintenance  effort  on  each 
project  should  be  conducted  so  as  to  determine  how  the  main- 
tenance time  is  actually  spent.  The  manager  can  then  have 
an  effective  tool  with  which  to  schedule  the  maintenance 
effort  without  having  to  resort  exclusively  to  the  use  of 
intuition. 

Programmers  should  be  trained  not  only  to  document  the 
system  as  it  develops,  but  to  do  so  keeping  the  maintenance 
aspect  in  mind.  Maintenance  enhancing  documentation  should 
be  developed  simultaneously  with  the  project  as  an  integral 
part    cf   the   system. 
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Programmers  must  become  aware  of  the  fact  that  there  is 
not  one  "best"  format  of  documentation  for  all  types  of 
maintenance.  More      research      like      the      General      Electric 

studies  should  be  conducted  in  order  to  determine  tha  best 
documentation  fcrmat  for  the  particular  maintenance  task 
being  performed.  A  particular  format,  then,  should  not  be 
taught   as  the   only    proper  way    to    document   a   program. 

Well  trained  programmers  will  also  raise  the  skill  level 
of  the  maintenance  team,  and  as  skill  level  increases,  the 
need    for      detailed    explicit      documentation    decreases.  The 

skilled  programmer  can  then  accept  larger  conceptual  ideas 
about  the  program,  thus  avoiding  the  need  to  search  through 
a  large  volume  of  information  in  order  to  perform  the  task 
at   hand.  Maintenance   and    cost   efficiencies      are   therefore 

enhanced. 

Since  programmers  have  more  confidence  in  internal  docu- 
mentation, it  is  recommended  that,  to  the  extent  feasible, 
information  be  carried  internally  along  with  the  source 
code.  as  "hard"  copies  are  needed,  they  could  simply  be 
printed  cut  for  a  specific  use.  Perhaps  a  physical  copy  of 
the  documentation  should  be  filed  for  back  up  purposes,  but 
the  amount  of  external  copies  shouli  be  kept  to  a  minimum  in 
order  to  avoid  the  reluctance  to  keep  the  hard  copies 
updated.  In  all  cases,  however,  all  forms  of  documentation 
should  be  updated  as  modifications  to  the  software  are  made 
in  order  to  ensure  that  the  docuaentaticn  is  an  accurate 
reflection    of  the  project. 

In  support  of  achieving  minimal  documentation,  the 
internally  stored  documentation  should  be  organized  in  the 
format  of  a  documentation  hierarchy.  There  should  be  one 
hierarchy  structure  that  will  contain  all  types  of  explicit 
documentation,  and  each  physical  format  will  be  classified 
and  filed  according  to  the  level  of  detail  contained  in  the 
document.    This    "level  of   detail"    type    of   categorization   will 
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necessarily  cause  the  documentation  to  become  a  part  of 
either  the  system  or  the  program  documentation. 

Users,  managers,  and  maintainors  should  be  able  to 
access  the  appropriate  piece  of  documentation  based  on  the 
amount  of  detail  needed  for  the  particular  task  at  hand. 
The  system  should  be  set  up  in  such  a  way  that  each  level  is 
easily  accessed,  and  a  method  of  moving  up  or  down  the  hier- 
archical organization  should  be  made  available. 

It  is  recommended  that  further  research  be  conducted 
into  the  implementation  of  the  hierarchical  scheme  in  a  menu 
driven  window  format,  that  can  display  the  indicated  piece  of 
documentation  on  a  display  screen  for  perusal.  A  pointer 
device  can  point  to  a  place  on  the  menu  to  request  a  partic- 
ular level  in  the  hierarchy.  The  capability  to  transcend  to 
different  levels  will  be  built  into  the  menu  operation  of 
the  windows.  This  documentation  hierarchy  implementation 
will  provide  a  powerful  documentation  tool  that  promotes  the 
minimal  documentation  concept,  and  should  result  in  an  effi- 
cient maintenance  effort. 
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